
## Introduction

Even well-written methods become hard to maintain when files and projects are organized inconsistently.

This post covers practical structure rules for teams.

## 1) Organize class members consistently

A common order:

1. constants / static readonly fields
2. private fields
3. constructors
4. public properties
5. public methods
6. private methods

Consistency reduces navigation time and review friction.

## 2) Keep related logic close together

Private helper methods should appear near the public method that uses them.

Avoid scattering related logic across long files.

## 3) One class per file (most of the time)

Use file names that match class names.

- `OrderService.cs` -> `OrderService`
- `OrderNotFoundException.cs` -> `OrderNotFoundException`

Exception: tiny related types such as a request record near a small service.

## 4) Avoid overusing regions

If a class requires many `#region` blocks to be readable, the class is likely too large.

Refactor by extracting smaller cohesive classes.

## 5) Keep project boundaries clear

A clean architecture baseline:

- Domain: entities, value objects, domain rules
- Application: use cases, DTOs, interfaces, validators
- Infrastructure: databases, external APIs, file storage
- WebApi: controllers, middleware, composition root

This separation makes ownership and dependencies explicit.

## 6) Comments: explain why, not what

### Bad comment

```csharp
// Check if user is admin
if (user.Role == Role.Admin)
{
    // ...
}
```

### Better code and better comment style

```csharp
if (user.IsAdmin)
{
    // Discount capped at 30% due to compliance policy REG-2024-117
    discount = Math.Min(discount, 0.30m);
}
```

Comment only when context or business rule is not obvious.

## 7) Document public APIs with XML comments

```csharp
/// <summary>
/// Retrieves an order by its unique identifier.
/// </summary>
/// <param name="id">The order ID.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>The order, or null if not found.</returns>
public Task<Order?> GetByIdAsync(int id, CancellationToken ct);
```

## 8) Delete commented-out code

Version control already preserves history. Dead commented blocks make files noisy and misleading.

## Summary

Code organization and documentation are force multipliers. Clear structure plus intentional comments makes large C# codebases easier to evolve safely.


Organize C# projects and classes for maintainability, and write comments that explain why instead of what.

C# Code Organization and Documentation Without Noise — Clean Code


## Introduction

Modern C# can remove boilerplate, but concise code is only useful when it remains clear and safe.

This post focuses on practical feature usage in production.

## 1) Records for immutable data

```csharp
public record OrderDto(int Id, string CustomerName, decimal Total);
public readonly record struct Money(decimal Amount, string Currency);
```

Use records for DTOs and value objects where immutability and value equality are beneficial.

## 2) Pattern matching for clearer branching

```csharp
public string GetStatusMessage(Order order) => order.Status switch
{
    OrderStatus.Pending => "Your order is being processed.",
    OrderStatus.Shipped => $"Shipped on {order.ShippedDate:d}.",
    OrderStatus.Delivered => "Delivered!",
    OrderStatus.Cancelled => "This order was cancelled.",
    _ => "Unknown status."
};
```

Compared to nested `if/else`, this is easier to scan and extend.

## 3) Collection expressions (C# 12)

```csharp
List<string> statuses = ["Active", "Inactive", "Pending"];
```

Prefer this syntax for concise collection initialization.

## 4) Raw string literals for SQL/JSON/templates

```csharp
string query = """
    SELECT Id, Name, Email
    FROM Customers
    WHERE IsActive = 1
    ORDER BY Name
    """;
```

Great for readability when strings contain quotes/newlines.

## 5) Primary constructors: when to use and avoid

Primary constructors reduce boilerplate, especially in DI-heavy services.

```csharp
public class OrderService(IOrderRepository repo, ILogger<OrderService> logger)
{
    public async Task<Order?> GetByIdAsync(int id, CancellationToken ct)
    {
        logger.LogInformation("Fetching order {OrderId}", id);
        return await repo.GetByIdAsync(id, ct);
    }
}
```

### Important tradeoff

Primary constructor parameters are captured and can be reassigned inside the class body.

If you need strict `readonly` guarantees, constructor validation, or overloads, prefer a traditional constructor with private `readonly` fields.

```csharp
public class PriceCalculator
{
    private readonly decimal _taxRate;

    public PriceCalculator(decimal taxRate)
    {
        ArgumentOutOfRangeException.ThrowIfNegativeOrZero(taxRate);
        _taxRate = taxRate;
    }
}
```

## Decision guide

Use **primary constructor** when:

- class is simple
- dependency injection is straightforward
- no complex initialization required

Use **traditional constructor** when:

- you need guard clauses and transformations
- you require `readonly` field safety
- you need multiple constructor overloads

## Summary

Modern C# features are powerful, but they are tools, not goals. Choose the feature that improves clarity and correctness for your specific class design.


Use modern C# features like records, pattern matching, collection expressions, and primary constructors without sacrificing maintainability.

Modern C# Features That Improve Code Readability — Clean Code


## Introduction

Testing is not separate from clean code. Code that is hard to test is usually tightly coupled or unclear.

## 1) Design for testability

### Inject dependencies

```csharp
public class TrialService(TimeProvider clock)
{
    public bool IsTrialExpired(User user)
        => clock.GetUtcNow() > user.TrialEndDate;
}
```

Avoid direct static/global dependencies such as `DateTime.Now` in business logic.

## 2) Follow AAA structure

- Arrange
- Act
- Assert

```csharp
[Fact]
public void CalculateTotal_WithDiscount_ReturnsDiscountedPrice()
{
    // Arrange
    var items = new List<OrderItem>
    {
        new("Widget", 100m, 2),
        new("Gadget", 50m, 1)
    };
    var calculator = new PriceCalculator(0.10m);

    // Act
    decimal total = calculator.CalculateTotal(items);

    // Assert
    total.Should().Be(225m);
}
```

## 3) Use descriptive test names

Pattern: `MethodName_Condition_ExpectedResult`

Examples:

- `GetByIdAsync_OrderNotFound_ReturnsNull`
- `Validate_EmptyCustomerId_ThrowsValidationException`
- `PlaceOrderAsync_ValidRequest_SavesAndNotifies`

## 4) Test behavior, not implementation details

Avoid brittle tests tied to internal method calls.

- Good: verify output, state change, emitted event, HTTP response
- Bad: over-verifying private interaction chains

## 5) Keep tests deterministic

Sources of flakiness:

- current time
- random values
- network dependencies
- shared mutable state

Use fakes/stubs/test containers and isolate external systems.

## 6) Fast feedback strategy

A practical test pyramid for C# backends:

- many unit tests (fast)
- fewer integration tests (database/API boundaries)
- minimal end-to-end tests (critical user flows)

## Summary

Testability is a design outcome. If dependencies are explicit and methods are cohesive, your tests become simpler, faster, and more valuable.


Write cleaner C# code by designing for testability and focusing tests on behavior using AAA and descriptive naming.

C# Testing and Testability for Maintainable Systems — Clean Code


## Introduction

Code smells are warning signs, not bugs by themselves. They indicate design debt that will slow future changes.

This post covers high-impact smells and corresponding refactors.

## 1) Long method -> Extract method

If a method exceeds one concern or one abstraction level, split it.

```csharp
public async Task PlaceOrderAsync(OrderRequest request, CancellationToken ct)
{
    ValidateRequest(request);
    var total = CalculateTotal(request.Items);
    var order = await PersistOrderAsync(request.CustomerId, total, ct);
    await SendConfirmationAsync(order, ct);
}
```

## 2) Data clumps -> Parameter object

Repeated parameter groups should become a type.

```csharp
public record Address(string Line1, string City, string ZipCode);
public record CreateUserRequest(string FirstName, string LastName, string Email, Address Address);
```

This improves consistency and reduces call-site errors.

## 3) Primitive obsession -> Value objects

Domain concepts should not always be `string`/`int`.

```csharp
public readonly record struct OrderId(int Value);
public readonly record struct CustomerId(int Value);
```

Compiler-checked types prevent ID mix-ups.

## 4) Magic numbers -> Named constants

```csharp
private const decimal BulkOrderThreshold = 500m;
private const decimal BulkDiscountRate = 0.10m;

if (order.Total > BulkOrderThreshold)
{
    order.Discount = order.Total * BulkDiscountRate;
}
```

Named constants explain intent and centralize change.

## 5) Duplicate code -> Extract shared function

```csharp
public static string FormatFullName(string? firstName, string? lastName)
    => string.IsNullOrWhiteSpace(firstName) && string.IsNullOrWhiteSpace(lastName)
        ? "Unknown"
        : $"{firstName} {lastName}".Trim();
```

Removing duplication lowers bug probability and maintenance cost.

## 6) Nested conditionals -> Guard clauses

```csharp
public decimal GetDiscount(Customer customer)
{
    if (customer is null) return 0m;
    if (!customer.IsActive) return 0m;

    return customer.OrderCount > 10 ? 0.15m : 0.05m;
}
```

Flat logic is easier to reason about and test.

## 7) Repeated type switch -> Polymorphism

If you repeatedly switch on type/enum to choose behavior, move behavior into subtype implementations.

```csharp
public abstract class PriceRule
{
    public abstract decimal Apply(decimal total);
}

public class StandardPriceRule : PriceRule
{
    public override decimal Apply(decimal total) => total;
}

public class PremiumPriceRule : PriceRule
{
    public override decimal Apply(decimal total) => total * 0.9m;
}
```

## Refactor safely checklist

- Add or update tests first
- Refactor in small commits
- Keep behavior unchanged
- Rename with intention
- Remove dead code after migration

## Summary

Refactoring is continuous, not a one-time event. Focus on smells that block change speed: long methods, duplication, primitive obsession, and nested conditionals.


Identify common C# code smells and apply practical refactoring patterns to improve readability, safety, and maintainability.

C# Code Smells and Refactoring Patterns That Matter — Clean Code


## Introduction

Clean methods help locally; clean class design helps globally.

When classes are too large or tightly coupled, every change becomes risky. This post shows practical class design rules based on SOLID.

## 1) Single Responsibility Principle (SRP)

A class should have one reason to change.

### Bad: one class does everything

```csharp
public class OrderService
{
    public void PlaceOrder(Order order)
    {
        Validate(order);
        Save(order);
        SendNotification(order);
    }
}
```

### Better: split by responsibility

```csharp
public class OrderValidator
{
    public void Validate(Order order) { /* ... */ }
}

public class OrderRepository
{
    public Task SaveAsync(Order order, CancellationToken ct) => Task.CompletedTask;
}

public class OrderNotifier
{
    public Task NotifyAsync(Order order, CancellationToken ct) => Task.CompletedTask;
}

public class OrderService(
    OrderValidator validator,
    OrderRepository repository,
    OrderNotifier notifier)
{
    public async Task PlaceOrderAsync(Order order, CancellationToken ct)
    {
        validator.Validate(order);
        await repository.SaveAsync(order, ct);
        await notifier.NotifyAsync(order, ct);
    }
}
```

## 2) Depend on abstractions, not concretions

High-level classes should not instantiate low-level dependencies directly.

```csharp
// BAD
public class SqlReportRepository
{
    public async Task<ReportData> GetDataAsync(int id, CancellationToken ct)
    {
        return new ReportData("Monthly Sales");
    }
}

public class ReportGenerator
{
    private readonly SqlReportRepository _repository;

    public ReportGenerator()
    {
        _repository = new SqlReportRepository();
    }

    public async Task<Report> GenerateAsync(int id, CancellationToken ct)
    {
        var data = await _repository.GetDataAsync(id, ct);
        return BuildReport(data);
    }

    private static Report BuildReport(ReportData data) => new(data.Title);
}

// GOOD
public interface IReportRepository
{
    Task<ReportData> GetDataAsync(int id, CancellationToken ct);
}

public class ReportGenerator(IReportRepository repository)
{
    public async Task<Report> GenerateAsync(int id, CancellationToken ct)
    {
        var data = await repository.GetDataAsync(id, ct);
        return BuildReport(data);
    }

    private static Report BuildReport(ReportData data) => new(data.Title);
}
```

This makes the class easier to test and swap implementations.

## 3) Prefer composition over inheritance

Inheritance can create brittle hierarchies.

```csharp
// BAD
public class FlyMovement
{
    public void Move() => Console.WriteLine("Flying");
}

public class WalkMovement
{
    public void Move() => Console.WriteLine("Walking");
}

public class Animal
{
    private readonly FlyMovement _flyMovement;
    private readonly WalkMovement _walkMovement;
    private readonly string _type;

    public Animal(string type)
    {
        _type = type;
        _flyMovement = new FlyMovement();
        _walkMovement = new WalkMovement();
    }

    public void Move()
    {
        if (_type == "Bird")
        {
            _flyMovement.Move();
        }
        else if (_type == "Dog")
        {
            _walkMovement.Move();
        }
    }
}


// GOOD
public interface IMovementStrategy
{
    void Move();
}

public class FlyMovement : IMovementStrategy
{
    public void Move() => Console.WriteLine("Flying");
}

public class WalkMovement : IMovementStrategy
{
    public void Move() => Console.WriteLine("Walking");
}

public class Animal(IMovementStrategy movement)
{
    public void Move() => movement.Move();
}
```

You can change behavior by changing strategy, not by rewriting class trees.

## 4) Keep classes cohesive

A cohesive class has members that all support one purpose.

Warning signs:

- class has multiple groups of unrelated fields
- methods only use a small subset of fields
- class keeps growing with `#region` blocks

When these appear, extract classes.

## 5) Open/Closed principle in practice

Avoid repeated `if/switch` chains that must be edited for each new type.

```csharp
public abstract class Shape
{
    public abstract double CalculateArea();
}

public class Circle(double radius) : Shape
{
    public override double CalculateArea() => Math.PI * radius * radius;
}

public class Rectangle(double width, double height) : Shape
{
    public override double CalculateArea() => width * height;
}
```

New behavior is added by extension, not by changing old code.

## Summary

Strong class design reduces coupling and change risk. Start with SRP and dependency inversion; these two practices usually deliver immediate maintainability gains.


Learn how to apply SRP, dependency inversion, and composition in C# to build maintainable, extensible production services.

C# Class Design and SOLID Principles in Real Projects — Clean Code


## Introduction

Most readability issues in C# code come from two places:

1. weak naming
2. methods doing too many things

If you improve only these two areas, your code quality rises quickly.

## 1) Naming conventions that scale

### Use `intention-revealing` names

A good name explains purpose without comments.

```csharp
// BAD
int d; // elapsed days

// GOOD
int elapsedTimeInDays;
```

### Follow C# casing conventions

- `PascalCase`: classes, methods, properties, constants
- `camelCase`: local variables, method parameters
- `_camelCase`: private fields

```csharp
public class OrderService
{
    private readonly IOrderRepository _orderRepository;

    public async Task<Order?> GetOrderByIdAsync(int orderId, CancellationToken ct)
    {
        var order = await _orderRepository.GetByIdAsync(orderId, ct);
        return order;
    }
}
```

### Prefer domain words over abbreviations

```csharp
// BAD
var custMgr = new CM();

// GOOD
var customerManager = new CustomerManager();
```

### Boolean names should read like questions

Good booleans: `isActive`, `hasPermission`, `canExecute`.

## 2) Method design principles

### Keep methods small and single-purpose

If a method validates input, calculates data, writes to database, and sends email, it has multiple responsibilities.

```csharp
public async Task ProcessOrderAsync(OrderRequest request, CancellationToken ct)
{
    Validate(request);
    decimal total = CalculateTotal(request.Items);
    var order = await SaveOrderAsync(request.CustomerId, total, ct);
    await NotifyCustomerAsync(order, ct);
}
```

### Keep parameter count low

When a method needs many primitives, introduce a request object.

```csharp
public record CreateUserRequest(
    string FirstName,
    string LastName,
    string Email,
    string Phone,
    Address Address);

public Task CreateUserAsync(CreateUserRequest request, CancellationToken ct);
```

### Avoid boolean flag arguments

```csharp
// BAD
RenderPage(page, true);

// GOOD
RenderPageForPrinting(page);
RenderPageForScreen(page);
```

### Use guard clauses to reduce nesting

```csharp
// BAD
public decimal GetDiscount(Customer customer)
{
    decimal discount = 0m;

    if (customer != null)
    {
        if (customer.IsActive)
        {
            if (customer.OrderCount > 10)
            {
                discount = 0.15m;
            }
            else
            {
                discount = 0.05m;
            }
        }
    }

    return discount;
}

// GOOD
public decimal GetDiscount(Customer customer)
{
    if (customer is null) return 0m;
    if (!customer.IsActive) return 0m;

    return customer.OrderCount > 10 ? 0.15m : 0.05m;
}
```

### Avoid hidden side effects

Method names must match behavior.

```csharp
// BAD
public bool CheckPassword(string password)
{
    if (Encrypt(password) == _storedHash)
    {
        Session.Initialize(); // hidden side effect
        return true;
    }
    return false;
}

// BETTER
public bool IsPasswordValid(string password) => Encrypt(password) == _storedHash;
public void InitializeSession() => Session.Initialize();
```

## Common review questions

Before merging, ask:

- Can a new developer understand each name in 5 seconds?
- Does each method do one thing at one abstraction level?
- Are there flag arguments or too many parameters?
- Are there side effects not reflected by method names?

## Summary

Clear naming and focused methods are the highest-ROI clean-code improvements in C#. Start there, then move to class design and architecture.


Practical C# naming conventions and method design rules that improve readability and reduce bugs in production code.

C# Naming Conventions and Method Design — Clean Code


## Why this series?

Writing code that "works" is not enough in production systems. Clean code makes your C# codebase easier to:

- maintain
- debug
- onboard new developers
- change safely as business rules evolve

This series breaks clean-code practices into small, practical topics with examples you can apply immediately.

## Series index

1. **Naming and Method Design**  
   Focus: naming conventions, small methods, guard clauses, parameter objects, avoiding side effects.

2. **Class Design and SOLID in Real Projects**  
   Focus: SRP, dependency inversion, composition over inheritance, and cohesive classes.

3. **Error Handling and Defensive Coding in ASP.NET Core**  
   Focus: specific exceptions, logging, `ProblemDetails`, request validation, and immutability.

4. **Code Smells and Refactoring Patterns**  
   Focus: long methods, primitive obsession, data clumps, duplicated code, magic numbers.

5. **Testing for Maintainability**  
   Focus: testable architecture, AAA, naming conventions for tests, behavior-first testing.

6. **Modern C# Features for Cleaner Code**  
   Focus: records, pattern matching, collection expressions, raw string literals, and primary constructors.

## Quick checklist

Use this list during code reviews:

- Are names intention-revealing?
- Are methods doing one thing?
- Are classes cohesive with one reason to change?
- Are expected failures handled without exceptions-for-flow?
- Are API errors returned with a consistent structure?
- Are business concepts modeled as types instead of plain `string`/`int`?
- Is logic tested through behavior, not implementation details?

## Suggested reading order

- Newer developers: 1 -> 2 -> 3 -> 5 -> 4 -> 6
- Experienced developers modernizing legacy code: 4 -> 2 -> 3 -> 5 -> 6 -> 1

## Final note

You do not need to apply everything at once. Improve code incrementally: one method, one class, one refactor at a time.


Start here for a practical C# clean code series focused on naming, methods, SOLID, error handling, testing, and modern C# features.